From my perspective, there is a fundamental difference between the guide this PR removes and the upstream README it now links to.

The README is essentially reference documentation.

The guide is intended to be a gradual introduction to the concept of auto-formatting nix projects. Especially useful for less experienced users.

I don't see why we couldn't have an FAQ entry that links to both the upstream README and the guide.

The guide is intended to be a gradual introduction to the concept of auto-formatting nix projects.

I disagree with that statement. I can't find anything in that text which is guide-like -- except for what is moved in this change to the FAQ -- and can't be found upstream.

I'd even go further and say that the current text makes appear problematic something that is not. This is not a productive style, not for guides and not for tutorials. Guides should merely give pointers for solving a generic problem -- the details are in reference documentation, and the FAQ answer guides users to go there. Tutorials should provide steps to solve a specific problem that introduces the learner to a recurring pattern of interactions. But there's nothing to learn about formatting, that's the whole point of automation. The current text has aspects of an explanation for why things are the way they are. That, if anywhere, could live in contributor-facing documentation next to the code we'd be asking people to in guides or tutorials.

My main argument though is the maintenance burden: There are so many ways to set up nixfmt, which will depend on your use case. And they're pretty nicely covered upstream -- why would we repeat any of that here? One thing nix.dev can be good for is recommending a known-good way of doing a particular thing, but given the variability here I personally don't want to step into that rabbit hole.

I'd appreciate an actual tutorial that sets up nixfmt with e.g. nixfmt-tree from nothing for a dummy project and shows all interactions. But that would look very different: with a clear learning objective, and without detours or information gaps. Until then, the guidance here is to point people to upstream.

That said, I'm not against making nixfmt more prominent or easy to find. By all means, please add an instruction to the packaging tutorial to run nixfmt at the end, or publish a blog post on nixos.org that we now have an official formatter. What I can also easily imagine is adding a section to set up nixfmt in your editor in a future tutorial on configuring vim with Nix.

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/formatting-team-meeting-2025-04-29/63649/1

My main argument though is the maintenance burden

If it helps, we (the formatting team) do consider any formatting related docs on nix.dev to be ours to maintain.

I'd appreciate an actual tutorial that sets up nixfmt with e.g. nixfmt-tree from nothing for a dummy project and shows all interactions

I would like to work on this next week. @fricklerhandwerk, would you be OK leaving things as they are until then? If not, then I'm also OK merging this PR.